Introduction

Users of IBM® Lotus® Expeditor, IBM Lotus Notes®, IBM Sametime®, and Lotus Symphony^TM frequently need to update their platforms to install new features or uninstall old features. The most common way to do these tasks is by using the Update Manager user interface (UI) provided by these applications.

Silent provisioning allows users to deploy features across multiple systems with much less user interaction. This article shows how you can deploy features by using DCommands.

We provide an example of the provisioning manifest to be used for DCommands along with details of the structure of the provisioning manifest. We also discuss how to control the target feature installation location and the usage of DCommands, with an explanation of the “provision” and “update” operations.

Using the Update Manager UI

In Lotus Expeditor, for example, you generally follow these steps to install new features:

1. Select File --- Application --- Install, and search for new features to install.
2. In the Feature Updates window, select the “Search for new features to install” radio button as shown in figure 1; click Next.

Figure 1. Feature Updates window



3. In the Application Locations window that displays, select the location for the available application and click OK, as shown in figure 2.

Figure 2. Application Locations window



4. In the Feature License window (see figure 3), select the features to install, accept the terms and conditions, and click Next.

Figure 3. Feature License window



5. The Installation window displays with a list of features that will be installed; click Finish (see figure 4).

Figure 4. Installation window



6. Select Add folder location --- Browse for folder, select the update site; click OK, and click Finish.
7. After the update process completes, restart the application so that your updates take effect by clicking the Restart Now button in the Restart window, as shown in figure 5.

Figure 5. Restart window



Now let's discuss how you can use DCommands to provision features into the platform silently, instead of using the Update Manager UI procedure.

Example provisioning manifest

The provisioning manifest, for example, install.update.xml, is an XML file that lists the features to be installed during the provisioning portion of the install process. An example install.update.xml for a provisioning manifest file is shown in listing 1.

Listing 1. install.update.xml code
Note these details about certain fields in this code:

• The action field indicates the action for the feature: enable, disable, install, or uninstall, as needed.
• The url field contains the location of the local or remote update site.
• If the value in the shared field is true, it indicates that the feature is to be installed in the shared folder.

Let's now examine the details of the structure of the install.update.xml file, line by line:

<?xml version="1.0" encoding="UTF-8"?> This is the root tag of the CA XML formatted file is.ibm-portal-composite.

<ibm-portal-composite >< domain-object name = "com.ibm.rcp.installmanifest"> This is the domain-object tag with value of the name attribute set to com.ibm.rcp.installmanifest, denoting that this is a provisioning manifest object.

<(object-data)>
<install>
<installfeature>
The list of features is equivalent to InstallShield features, which later can be presented as a list from which users can choose to install certain features. This installfeature tag has the following attributes:

• The mergeaction attribute is processed only from the new provisioning manifest and is ignored in the old manifest.

• add. Forces an installfeature specified in the new provisioning manifest file to be retained in the merged result.

• remove. Forces an installfeature specified in the new provisioning manifest file to be removed from the merged result.

• If the mergeaction attribute is not present, then the features within the installfeature are processed against the install feature of the identical ID.

< requirements> The requirements tag denotes a requirements block that contributes a list of required features to be used by the provisioning system.

< (feature)> The feature tag denotes a feature that is required by the platform for a given deployment. This tag has the following attributes:

• the mergeaction attribute not specified, then the feature is retained with the attributes define in the new manifest.
• mergeaction = "add", then the new feature is retained completely.
• mergeaction = "remove", then the feature is removed.

• If the installfeature is present in the old manifest and does not exist in the new manifest, it will be retained completely.

The rest of the code is as follows:

Controlling the feature installation location

This section explains the available methods for controlling and specifying the target installation site for a feature. The platform provisioning system defines by default the following target sites into which features are installed:
The target installation site for a particular feature is determined by evaluating several conditions, including whether the feature is currently installed, collocation affinity, ability to write a specific directory, and requested target site.

Collocation affinity is an attribute that can be specified by each feature in the feature.xml descriptor and specifies the ID of another feature. It directs the provisioning system to attempt to install the new feature into the same target site that the other feature, that is, the feature whose ID is specified in the feature.xml, uses.

Using the Feature Manifest Editor from the Plug-in Development Environment, we can specify the collocation affinity on the Installation page of the Editor.

For example, suppose that a feature with an ID of com.ibm.sample has been installed in the shared site. A new feature with an ID of com.ibm.extendedsample can then specify a collocation affinity of com.ibm.sample to request that the feature is installed in the same location as com.ibm.sample, as shown in listing 2.

Listing 2. com.ibm.extended sample code
The platform provisioning system uses these decisions to determine the target site for a feature, following this process:

1. If a provisioning system detects a version of the feature that is already installed, the same installation site is used for any additional versions. This decision applies only when the feature has been installed into the Eclipse, RCP, or shared target sites.

3. If a specific target site is requested for the feature, then attempt to install the feature into this site. If that site is not accessible, then continue with step 5. A target site can be specified only for features distributed through the Eclipse feature distribution job using the Device Management server.

4. If the provisioning manifest or a ProvisioningRequest (provided through an API request) specifies shared = true, then the shared site is the desired target site for installing the feature. If that site is not accessible, then continue with step 5.

5. If the provisioning manifest or a ProvisioningRequest object specifies shared = false or, if because of accessibility issues, the desired target sites for steps 3 and 4 are not available, then attempt to install the feature in the user site.

Because the collocation affinity takes precedence over the target site or shared attribute specification, specifying a collocation affinity is the preferred model for controlling feature installation locations. The client platform has defined the following features that can be used as targets for the collocation affinity attribute:
If the platform is used only by a single user with a single workspace, then the target site for a feature is less important because all features are always available. In the multi-user configuration, however, the target installation site becomes much more important because some applications are shared among all users of the platform, while other applications are private to specific users.

For example, assume a multi-user configuration in which deployers have administrator rights to the shared directory, and ordinary users are limited to read-only rights. Feature W does not contain a collocation affinity attribute.

If a deployer attempts to install this feature, it is installed into the shared directory because this location is the default option with no collocation affinity and no target site specified.

However, if a user attempts to install this feature, it is installed in the user target site and cannot be shared by all users on the platform. The user site is selected because the shared site is not accessible.

To limit the ability of a specific user to install feature W into the user site, the deployer can specify a collocation affinity attribute with the ID, com.ibm.rcp.site.anchor.shared.feature. The resultant site for a deployer is still the shared site, chosen now not because it is the default, but because the collocation affinity selects that site.

If a user attempts to install the feature, the installation will fail because the site specified by the collocation affinity is not accessible.

Using the provisioning application with DCommands

Per the InfoCenter topic, “Using the Provisioning application with Dcommands:”
where

<command> can be update, provision <file_name> for the installation and uninstallation of features, and <file> is the log file that is generated.

This code generates either of these results:

• The existing platform (currently running the workbench) is passed the provisioning arguments, and the provisioning occurs inside the existing platform. When provisioning is complete, the existing platform continues to run until the user currently using the platform decides to shut down.

• A new instance of the platform starts using the provisioning application, and the provisioning occurs using this new instance of the platform. When provisioning is complete, the platform exits.

The update operation processes the provisioning manifest. If an install.update.xml file is present in the same directory as the provisioning manifest, then the contents are merged prior to processing the provisioning manifest to perform any updates.

The provision operation processes the provisioning manifest supplied as an argument on the command and processes the features contained within the provisioning manifest. Contents of the supplied provisioning manifest file are not merged with the version defined by the platform, and there are no changes to the provisioning.manifest.version property in the rcplauncher.properties file.

For the two example operations below you can use the sample install.update.xml from listing 1.

a) Example command using the update operation:
b) Example command using provision<file_name > operation:
Figure 6. Example command in operation



Figure 7 shows the features installed on the platform after the command is executed.

Figure 7. Features installed on the platform



Examples for the provisioning of Notes plug-ins:

1. Using the update option:

• The install.update.xml file mentioned in listing 1 can be used as an example for this option, and it is placed in C:\Program Files\IBM\Lotus\Notes\framework\rcp\deploy, that is, in the Notes installed location\ framework\rcp\deploy directory.

• The batch file can be as follows:

2. Using the provision <file_name> option, which is recommended:

• The batch file can be as follows:

NOTE: If the features are unsigned or untrusted, they are not installed when Lotus Notes is down. When Lotus Notes is running, it prompts the user to confirm whether to continue with the installation.

Conclusion

Silent provisioning allows us to deploy features across multiple systems and requires much less user interaction. It also allows us to use multiple options provided by provisioning that are not available when using the Update Manager UI.

Resources

Lotus Expeditor 6.2 InfoCenter topic, “Using the provisioning application for multi-user configurations”:
http://publib.boulder.ibm.com/infocenter/ledoc/v6r2/index.jsp?topic=/com.ibm.rcp.tools.doc.admin/provisioningappusingProvisioninginterfaces_usingProappMU.html

Lotus Expeditor 6.2 InfoCenter topic, “Using the global install handler (the mergemanifest portion)”:
http://publib.boulder.ibm.com/infocenter/ledoc/v6r2/index.jsp?topic=/com.ibm.rcp.tools.doc.admin/globalinstallhandler_creatinginstrfile.html

developerWorks Lotus Expeditor product page:
http://www.ibm.com/developerworks/lotus/products/expeditor/

About the authors

Sujith Job joined IBM in 2003 and currently works on the Lotus Expeditor team at IBM's India Software Labs in Pune, focusing on Eclipse, Java^TM, Android, WebSphere® Portal and Lotus Expeditor. He also assists customers in creating innovative applications using the Lotus Expeditor framework to solve real-life business problems. Prior to this role, he worked as worldwide lead for the Lotus Expeditor L3 team. You can reach him at sujithjob@in.ibm.com.

Minakshi C. Korad has worked at IBM's India Software Lab in Pune since July 2009 where she is currently a member of the Lotus Expeditor Client Support team, handling Lotus Expeditor Server development, test, and support. Her areas of focus include Eclipse-based technologies, Web technologies, Lotus Expeditor on desktops and devices, and Lotus Expeditor provisioning. You can reach her at minakshikorad@in.ibm.com.